<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Performing Backups</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Getting Started with Berkeley DB, Java Edition Transaction Processing" />
    <link rel="up" href="jebackuprestore.html" title="Chapter 5. Backing up and Restoring Berkeley DB, Java Edition Applications" />
    <link rel="prev" href="chkpoint.html" title="Checkpoints" />
    <link rel="next" href="jecatastrophicrecovery.html" title="Performing Catastrophic Recovery" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Performing Backups</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="chkpoint.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 5. Backing up and Restoring Berkeley DB, Java Edition Applications</th>
          <td width="20%" align="right"> <a accesskey="n" href="jecatastrophicrecovery.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="backup"></a>Performing Backups</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <dl>
          <dt>
            <span class="sect2">
              <a href="backup.html#partialBackup">Performing a Hot Backup</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="backup.html#completeBackup">Performing an Offline Backup</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="backup.html#dbbackuphelper">Using the DbBackup Helper Class</a>
            </span>
          </dt>
        </dl>
      </div>
      <p>
            This section describes how to backup your JE database(s) such that catastrophic recovery is possible.
        </p>
      <p>
                To backup your database, you can either take a hot backup
                or an offline backup. A hot backup is performed while 
                database write operations are in progress. 
        </p>
      <p>
            Do not confuse offline and hot backups with the concept of a
            full and incremental backup.  Both an offline and a hot backup
            are full backups – you back up the entire database. The
            only difference between them is how much of the contents of the
            in-memory cache are contained in them. On the other hand, an
            incremental backup is a backup of just those log files modified
            or created since the time of the last backup.  Most backup
            software is capable of performing both full and incremental
            backups for you.
        </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="partialBackup"></a>Performing a Hot Backup</h3>
            </div>
          </div>
        </div>
        <p>
                To perform a hot backup of your JE databases, copy all log files 
                (<code class="filename">*.jdb</code> files) from your environment directory to
                your archival location or backup media. The files must be copied
                in alphabetical order (numerical in effect). You do not have to 
                stop any database operations in order to do this.
            </p>
        <p>
               To make this process a bit easier, you may want to make use of the
               <code class="classname">DbBackup</code> helper class. See
               <a class="xref" href="backup.html#dbbackuphelper" title="Using the DbBackup Helper Class">Using the DbBackup Helper Class</a>
               for details.
            </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="completeBackup"></a>Performing an Offline Backup</h3>
            </div>
          </div>
        </div>
        <p>
                An offline backup guarantees that you have captured the database in its entirety, including all contents
                of your in-memory cache, at the moment that the
                backup was taken. To do this, you must make sure that no write operations are in progress and all
                database modifications have been written to your log files
                on disk.  To obtain an offline backup:
			</p>
        <div class="orderedlist">
          <ol type="1">
            <li>
              <p>
                        Stop writing your databases. 
                    </p>
            </li>
            <li>
              <p>
                        Make sure all your in-memory changes have been flushed to disk. How you do this depends on the
                        type of transactions that you are using:    
                    </p>
              <div class="itemizedlist">
                <ul type="disc">
                  <li>
                    <p>
                                If you are using transactions that writes all dirty data to disk on commit (this is the default
                                behavior), you simply need to make sure all on-going transactions are committed or
                                aborted.
                            </p>
                  </li>
                  <li>
                    <p>
                                If you are using transactions that do not synchronously write on commit, you must 
                                run a checkpoint.
                                Remember that closing your environment causes a checkpoint to be run, so if your
                                application is shutting
                                down completely before taking the backup, you have met this requirement.
                            </p>
                    <p>
                                For information on changing the transactional sync behavior, see
                                <a class="xref" href="nodurabletxn.html" title="Non-Durable Transactions">Non-Durable Transactions</a>.
                                For information on running a checkpoint, see
                                <a class="xref" href="chkpoint.html" title="Checkpoints">Checkpoints</a>.
                            </p>
                  </li>
                </ul>
              </div>
            </li>
            <li>
              <p>
                        If you are using durable transactions, then optionally 
                        run a checkpoint. Doing this can shorten the time
                        required to restore your database from this back up.
                    </p>
            </li>
            <li>
              <p>
                        Copy all log files (<code class="filename">*.jdb</code>) from your environment directory to your archival
                        location or backup media.
                        To make this process a bit easier, you may want to make use of the
                        <code class="classname">DbBackup</code> helper class. See
                        the next section for details.
                    </p>
            </li>
          </ol>
        </div>
        <p>
                You can now resume normal database operations.
            </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="dbbackuphelper"></a>Using the DbBackup Helper Class</h3>
            </div>
          </div>
        </div>
        <p>
                        In order to simplify backup operations, JE
                        provides the <code class="classname">DbBackup</code> helper
                        class. This class stops and restarts JE background activity 
                        in an open environment. It also lets the application create a 
                        backup which can support restoring the environment to 
                        a specific point in time.
                </p>
        <p>
                    Because you do not have to stop JE write activity
                    in order to take a backup, it is usually necessary to
                    examine your log files twice before you decide that
                    your backup is complete. This is because JE may
                    create a new log file while you are running your
                    backup. A second pass over your log files allows you to
                    ensure that no new files have been created and so you
                    can declare your backup complete.
                </p>
        <p>
                    For example:
                </p>
        <pre class="programlisting"> time    files in                    activity
         environment

  t0     000000001.jdb     Backup starts copying file 1
         000000003.jdb
         000000004.jdb

  t1     000000001.jdb     JE log cleaner migrates portion of file 3 to
         000000004.jdb     newly created file 5 and deletes file 3. 
         000000005.jdb     Backup finishes file 1, starts copying file 4.
                           Backup MUST include file 5 for a consistent 
                           backup!

  t2     000000001.jdb     Backup finishes copying file 4, starts and 
         000000004.jdb     finishes file 5, has caught up. Backup ends.
         000000005.jdb
</pre>
        <p>
                    <code class="classname">DbBackup</code> works around this
                    problem by defining the set of files that must be
                    copied for each backup operation, and freezes all
                    changes to those files. The application can copy that
                    defined set of files and finish operation without
                    checking for the ongoing creation of new files. Also,
                    there will be no need to check for a newer version of
                    the last file on the next backup.
            </p>
        <p>
                    In the example above, if <code class="classname">DbBackup</code> was used at t0,
                    the application would only have to copy files 1, 3 and
                    4 to back up. On a subsequent backup, the application
                    could start its copying at file 5. There would be no
                    need to check for a newer version of file 4.
            </p>
        <p>
                The following code fragment illustrates this class' usage:
            </p>
        <pre class="programlisting">package je.gettingStarted;

...
import com.sleepycat.je.util.DbBackup;
...

    Environment env = new Environment(...);
    DbBackup backupHelper = new DbBackup(env);

    // Find the file number of the last file in the previous backup
    // persistently, by either checking the backup archive, or saving
    // state in a persistent file.
    long lastFileCopiedInPrevBackup =  ...

    // Start backup, find out what needs to be copied.
    backupHelper.startBackup();
    try {
        String[] filesForBackup =
          backupHelper.getLogFilesInBackupSet(lastFileCopiedInPrevBackup);

        // Copy the files to archival storage.
        myApplicationCopyMethod(filesForBackup)
        // Update our knowlege of the last file saved in the backup set,
        // so we can copy less on the next backup
        lastFileCopiedInPrevBackup = backupHelper.getLastFileInBackupSet();
        myApplicationSaveLastFile(lastFileCopiedInBackupSet);
    }
    finally {
        // Remember to exit backup mode, or all log files won't be cleaned
        // and disk usage will bloat.
       backupHelper.endBackup();
   } </pre>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="chkpoint.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="jebackuprestore.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="jecatastrophicrecovery.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Checkpoints </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Performing Catastrophic Recovery</td>
        </tr>
      </table>
    </div>
  </body>
</html>
